calculate_stochastic_quantities()

Домен: SIMULATION | Контур: Квантование и расчет веса продуктов

WarningОграничение публичной документации

В открытом доступе представлена демонстрационная версия метода. В настоящей публичной документации отображены не все шаги, технические сценарии и приватные эндпоинты для системы цифровых симуляторов бизнес-процессов.

  • Полная спецификация метода: Будет доступна только во внутреннем контуре разработки (Confluence / Swagger Enterprise).

1. Бизнес-спецификация метода

  • Идентификатор метода: BPDS-SIM-M010
  • Системное имя: calculate_stochastic_quantities(sku: String): BigDecimal
  • Микросервис: simulation-core-engine
  • Домен: SIMULATION
  • Класс / Компонент: simulation.engine.helpers.WeightQuantizer

1.1. Описание логики работы

Этот метод отвечает за расчет точного количества или веса конкретного продукта, который пользователь кладет в корзину при покупке (или списывает при готовке). Метод получает на вход уже выбранный строковый артикул товара (SKU) и выполняет его текстовый анализ.

Логика разделения типов продуктов: 1. Штучный товар: Если артикул продукта (SKU) не имеет специального признака веса (например, молоко MILK_AMAL_1L_3.2), симулятор фиксирует объем ровно в 1.0000 штуку. 2. Весовой товар: Если артикул продукта (SKU) заканчивается на маркер веса _KG (например, бананы BANANA_ECUADOR_KG), симулятор имитирует весы торгового зала. Он генерирует случайный вес в реалистичном диапазоне от 500 грамм до 3.5 кг. Чтобы итоговая стоимость чеков в тенге не завышалась искусственно при округлениях, к весу применяется правило округления к ближайшему четному знаку (метод HALF_EVEN) строго до 4 знаков после запятой (например, сгенерированный вес 1.69505 кг превратится в чеке в 1.6950 кг).

1.2. Пошаговое выполнение

  1. Анализ строкового артикула: Метод принимает строку sku и проверяет её окончание. Если строка не заканчивается на суффикс _KG, продукт признается штучным.
  2. Штучная фиксация: Для штучного товара метод сразу возвращает значение 1.0000 в формате точного финансового числа (BigDecimal) со шкалой в 4 знака.
  3. Стохастическая генерация веса: Для весовых позиций запускается случайный генератор, который выдает дробное число в диапазоне от 0.5000 до 3.5000 кг.
  4. Банковское округление: Сгенерированное число переводится в формат BigDecimal и округляется по правилу ближайшего четного знака (RoundingMode.HALF_EVEN) ровно до 4 знаков после запятой.
  5. Выход: Готовое значение объема/веса возвращается вызвавшему его прикладному хелперу.

2. Диаграмма последовательности метода (Вход и Выход флоу)

Диаграмма наглядно показывает, как метод принимает строковый артикул товара, анализирует его текстовый суффикс, проводит округление на уровне процессора и возвращает точный объем.

sequenceDiagram
    autonumber
    participant Caller as Прикладной Хелпер Сценария
    participant Q as WeightQuantizer
    participant Math as Математический Движок

    %% ВХОД МЕТОДА
    Caller->>Q: Вызов calculateStochasticQuantities(sku)
    activate Q
    Note over Q: Вход метода: Строковый артикул товара (SKU) как готовый параметр

    alt Ситуация 1: Товар штучный (имя SKU НЕ заканчивается на _KG)
        Note over Q: Фиксация базового объема для штучной позиции
        Q-->>Caller: Выход метода: Объем равен 1.0000 (BigDecimal)
    else Ситуация 2: Товар весовой (имя SKU заканчивается на _KG)
        Q->>Q: Генерация случайного double в диапазоне от 0.5 до 3.5
        
        %% МАТЕМАТИЧЕСКОЕ ОКРУГЛЕНИЕ
        Q->>Math: Перевод в BigDecimal и округление setScale(4, HALF_EVEN)
        activate Math
        Math-->>Q: Возврат: Округленный до 4 знаков вес
        deactivate Math
        
        Note over Q: Выход метода: Точный квантованный вес весового товара
        Q-->>Caller: Вывод метода: Вес товара (BigDecimal)
    end
    deactivate Q

3. Схемы данных и SQL-взаимодействие

Этот метод рассчитывает промежуточные объемы товаров исключительно внутри оперативной памяти и напрямую к PostgreSQL запросы не отправляет. Его задача — выдать математически точный объем для формирования тела запросов.

4. Спецификация обмена данными (Вход / Выход)

Данные передаются внутри памяти микросервиса simulation-core-engine в рамках локального потока выполнения.

4.1. Входной параметр (Передается аргументом при вызове)

{
  "incoming_sku_string": "BANANA_ECUADOR_KG"
}

4.2. Выходной параметр (Возвращается из метода)

{
  "quantized_quantity": 1.6950,
  "data_type": "java.math.BigDecimal",
  "rounding_mode": "HALF_EVEN",
  "scale": 4
}

5. ЗАДАЧА ДЛЯ РАЗРАБОТЧИКА: BACKEND

Заголовок: Реализация компонента квантования веса товаров calculate_stochastic_quantities с округлением к ближайшему четному

5.1. Что нужно сделать

  1. Написать Java-класс WeightQuantizer в пакете simulation.engine.helpers и пометить его аннотацией @Component.
  2. Реализовать проверку суффикса артикула: если строка sku не оканчивается на _KG (без учета регистра), возвращать константу BigDecimal.valueOf(1.0000).setScale(4).
  3. Для весовых товаров использовать высокопроизводительный потокобезопасный генератор ThreadLocalRandom.current().nextDouble(0.5, 3.5).
  4. Запретить передачу сырого числа double в конструктор new BigDecimal(). Сначала переводить сгенерированный вес в строку через Double.toString() или использовать безопасный фабричный метод BigDecimal.valueOf(rawWeight).
  5. Установить точность поля ровно в 4 знака после запятой с типом округления к ближайшему четному: .setScale(4, RoundingMode.HALF_EVEN).

6. ЗАДАЧА ДЛЯ РАЗРАБОТЧИКА: МИГРАЦИЯ

Заголовок: Обновление типа точности колонок количества товаров в базе данных бэкенда приложения

6.1. Что нужно сделать

Чтобы веса с точностью до 4 знаков, сгенерированные симулятором, успешно записывались в приложение и не вызывали ошибок усечения данных на стороне базы данных бэкенда, необходимо актуализировать структуру таблиц public в PostgreSQL бэкенда розничной сети Алматы. Задача миграции — перевести тип колонки quantity на денежно-весовой стандарт BPDS.

-- Изменения для продуктивной базы данных бэкенда розничной сети (схема public)
ALTER TABLE public.fridge_products 
ALTER COLUMN quantity TYPE NUMERIC(10, 4);

-- Защитный барьер на уровне СУБД: вес купленного товара обязан быть больше нуля
ALTER TABLE public.fridge_products 
ADD CONSTRAINT chk_positive_quantity CHECK (quantity > 0.0000);